home *** CD-ROM | disk | FTP | other *** search
/ NeXT Education Software Sampler 1992 Fall / NeXT Education Software Sampler 1992 Fall.iso / Programming / Classes / SocketClasses / doc / ascii / SktSocketUser.spec < prev   
Encoding:
Text File  |  1992-03-28  |  17.3 KB  |  511 lines
  1. Copyright 1992 by Nik A Gervae.  This is part of the documentation for
  2. the socket classes, which are licensed under the terms of the GNU General
  3. Public License as published by the Free Software Foundation.
  4.  
  5. The documented program and this documentation are distributed in the hope
  6. that it will be useful, but are provided "AS IS" AND WITHOUT ANY WARRANTY;
  7. without any express or implied warranty of MERCHANTABILITY or FITNESS FOR
  8. A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  9. Any use or distribution of the program and documentation must include
  10. appropriate copyrights to acknowledge Nik A. Gervae and the Free Software
  11. Foundation, Inc.
  12.  
  13. You should have received a copy of the GNU General Public License
  14. along with this documentation; if not, write to the Free Software
  15. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16.  
  17. ===============
  18.  
  19. SktSocketUser
  20.  
  21. INHERITS FROM    Object
  22.  
  23. DECLARED IN    SktSocketUser.h
  24.  
  25.  
  26.  
  27. CLASS DESCRIPTION
  28.  
  29. The SktSocketUser class, together with the SktSocketManager and 
  30. SktSocket classes, provides an application with the ability to act as a 
  31. server for Berkeley UNIX stream socket connections.  It can also work 
  32. with an SktSocket alone in a client application.  SktSocketUser is an 
  33. abstract superclass providing retrieval of an associated SktSocket's input 
  34. and return of output to that SktSocket for queuing.  The actual processing 
  35. of input must be implemented in a subclass or category.
  36.  
  37. An SktSocketUser object is created by the application's 
  38. SktSocketManager after an SktSocket is created.  After that, however, the 
  39. SktSocketManager has nothing further to do with it.  You are responsible 
  40. for having your subclass process its input, either by sending it update 
  41. messages in the same style as the SktSocketManager's update method, 
  42. or by using a timed entry within your subclass.  Leaving control for an 
  43. SktSocketUser outside of the SktSocketManager gives the definer of the 
  44. subclass more control over its actions; you may want to suspend 
  45. processing on some SktSocketUsers, for example.  In each update cycle, 
  46. the SktSocketUser can simply get an input line (or more), process it, and 
  47. have its associated SktSocket queue the output.
  48.  
  49. An SktSocketUser provides several different ways to access its input 
  50. queue.  It can be treated as a simple buffer of characters, from which you 
  51. always draw a specified amount.  It can also be treated as a set of “lines” 
  52. delimited by a character you specify (the default, of course, is linefeed).  
  53. And last, it can be told on demand to get all input characters up to and 
  54. including a specific character (byte value).  These last two access 
  55. methods also allow for stripping of the delimiter in the returned data.
  56.  
  57. For more information on sockets, see: the related UNIX man pages; “An 
  58. Introductory 4.3BSD Interprocess Communication Tutorial” (reprinted in 
  59. UNIX Programmer's Supplementary Documents Volume 1, PS1:7); or, 
  60. “An Advanced 4.3BSD Interprocess Communication Tutorial” (reprinted 
  61. in UNIX Programmer's Supplementary Documents Volume 1, PS1:8).
  62.  
  63. See also: SktSocketManager, SktSocket
  64.  
  65.  
  66.  
  67. INSTANCE VARIABLES
  68.  
  69. Inherited from Object    Class    isa;
  70.  
  71. Declared in SktSocketUser    SktSocket    *socket;
  72.                 BOOL        doesStrip;
  73.                 BOOL        doesStripCRLF;
  74.                 char        delimiter;
  75.                 char        *inputQueue;
  76.                 long int    queueLength;
  77.                 long int     queueLimit;
  78.                 NXZone        *zone;
  79.  
  80. socket         The SktSocketUser object's SktSocket.
  81.  
  82. doesStrip     Whether to strip the delimiter/requested char 
  83.         on retrieval by line/character.
  84.  
  85. doesStripCRLF     YES if carriage returns and linefeeds are 
  86.         stripped in addition to any delimiters.
  87.  
  88. delimiter     The character used to determine what a line 
  89.         is (defaults to linefeed).
  90.  
  91. inputQueue     Strings waiting to be processed.
  92.  
  93. queueLength     The length, in bytes, of the input queue.
  94.  
  95. queueLimit     The maximum number of delimiters allowed 
  96.         in the input queue at any one time.
  97.  
  98. zone        The zone that the SktSocket was allocated 
  99.         from.
  100.  
  101.  
  102.  
  103. METHOD TYPES
  104.  
  105. Initializing and freeing a SktSocketUser object
  106. - initWithSocket:
  107. - init
  108. - free
  109.  
  110. Modifying SktSocketUser attributes
  111. - setDelimiter:
  112. - delimiter
  113. - setDoesStrip:
  114. - doesStrip
  115. - setDoesStripCRLF:
  116. - doesStripCRLF
  117. - setQueueLimit:
  118. - queueLimit
  119. - setSocket:
  120. - socket
  121.  
  122. Managing input and output
  123. - queueInput:
  124. - purgeInput
  125. - queueOutput:ofLength:
  126. - queueOutputString:
  127.  
  128. Retrieving input
  129. - getInput:ofLength:
  130. - ungetInput:ofLength:
  131. - getAllInput:
  132. - inputToChar:
  133. - inputToChar:inZone:
  134. - nextInputLine
  135. - nextInputLineinZone:
  136.  
  137.  
  138.  
  139. INSTANCE METHODS
  140.  
  141.  
  142.  
  143. delimiter:
  144. - (char)delimiter
  145.  
  146. Returns the character used to delimit lines in the nextInputLine and 
  147. nextInputLineInZone: methds.  The default is the linefeed character 
  148. (`\n').
  149.  
  150. See also: - delimiter, - nextInputLine,- nextInputLineInZone:
  151.  
  152.  
  153.  
  154. doesStrip:
  155. - (BOOL)doesStrip
  156.  
  157. Returns YES if the SktSocketUser strips the ...ToChar: character from 
  158. input requested by inputToChar: and inputToChar:inZone:, or the 
  159. delimiter from input requested by nextInputLine and 
  160. nextInputLineInZone:.  If NO, stripping is not done in those methods.  
  161. However, if the ...ToChar: character or the delimiter is either a carriage 
  162. return or a linefeed, and doesStripCRLF is YES, then those will be 
  163. stripped.
  164.  
  165. See also: - setDoesStrip:, - setDoesStripCRLF: - doesStripCRLF
  166.  
  167.  
  168.  
  169. doesStripCRLF
  170. - (BOOL)setDoesStripCRLF
  171.  
  172. Returns YES if the SktSocketUser strips all trailing carriage returns and 
  173. linefeeds from input retrieved by any of the inputToChar... or 
  174. nextInputLine... methods.  This stripping is performed after regular 
  175. stripping, so that if regular stripping is not done and the character used to 
  176. retrieve the text is not a carriage return or linefeed, CRLF stripping is 
  177. blocked from occurring.  Returns self.
  178.  
  179. See also: - setDoesStripCRLF, - setDoesStrip: - doesStrip
  180.  
  181.  
  182.  
  183. free
  184. - free
  185.  
  186. Deallocates the storage occupied by the SktSocketUser.
  187.  
  188.  
  189.  
  190. getAllInput:
  191. - (long int)getInput:(char **)input
  192.  
  193. Places the entire contents of the input queue in *input.  Returns the 
  194. number of bytes in the queue.  If you want to be sure there is anything in 
  195. the queue before you try to get anything, send a queueLength message.
  196.  
  197. If a memory reallocation fails, this method returns -1.  If the return value 
  198. is -1, the SktSocketUser has become corrupt, and will crash the process 
  199. the next time it attempts to alter its input queue.  You should either free 
  200. the SktSocket or terminate the process.
  201.  
  202. See also:  - queueLength, - getInput:ofLength:, 
  203. - ungetInput:ofLength:, - inputToChar:, - inputToChar:inZone:, 
  204. - nextInputLine, - nextInputLineInZone:, 
  205.  
  206.  
  207.  
  208. getInput:ofLength:
  209. - (long int)getInput:(char *)input ofLength:(long int)length
  210.  
  211. Removes up to length bytes from the input queue and places them in the 
  212. buffer specified by input.  Returns the number of bytes actually retrieved 
  213. (this may be less than the number requested).  If you want to be sure there 
  214. is enough in the queue before you try to get anything, send a 
  215. queueLength message.
  216.  
  217. If a memory reallocation fails, this method returns -1.  If the return value 
  218. is -1, the SktSocketUser has become corrupt, and will crash the process 
  219. the next time it attempts to alter its input queue.  You should either free 
  220. the SktSocket or terminate the process.
  221.  
  222. See also: - queueLength, - ungetInput:ofLength:, - getAllInput:, 
  223. - inputToChar:, - inputToChar:inZone:, - nextInputLine, 
  224. - nextInputLineInZone:, 
  225.  
  226.  
  227.  
  228. init
  229. - init
  230.  
  231. Initializes the socket user to have no SktSocket.  Returns self.
  232.  
  233. See also: - initWithSocket:
  234.  
  235.  
  236.  
  237. initWithSocket:
  238. - initWithocket:(SktSocket *)aSocket
  239.  
  240. Initializes the socket user to use aSocket as its SktSocket.  The SktSocket 
  241. also has its user set to the SktSocketUser.  This method is the designated 
  242. initializer for SktSocketUser objects.  Returns self, or nil if the output 
  243. queue can't be allocated.
  244.  
  245. See also: - init, - setSocket:, - socket
  246.  
  247.  
  248.  
  249. inputToChar:
  250. - (char *)inputToChar:(char)aChar
  251.  
  252. Removes characters from the input queue up to and including aChar, and 
  253. returns them as a null-terminated string.  If regular stripping is enabled, 
  254. aChar is removed from the string.  Further, if CRLF stripping is enabled, 
  255. any trailing carriage returns or linefeeds are removed.  If no string is 
  256. found, or if the string found is completely stripped, this method returns an 
  257. empty string.
  258.  
  259. If a memory reallocation fails, this method returns NULL.  If the return 
  260. value is NULL, the SktSocketUser has become corrupt, and will crash the 
  261. process the next time it attempts to alter its input queue.  You should 
  262. either free the SktSocket or terminate the process.
  263.  
  264. See also: - getInput:ofLength:, - inputToChar:inZone:, 
  265. - nextInputLine, - nextInputLineInZone:, - setDoesStrip:, 
  266. - doesStrip, - setDoesStripCRLF:, - doesStripCRLF
  267.  
  268.  
  269.  
  270. inputToChar:inZone:
  271. - (char *)inputToChar:(char)aChar inZone:(NXZone *)aZone
  272.  
  273. Removes characters from the input queue up to and including aChar, and 
  274. returns them as a null-terminated string allocated from aZone.  If regular 
  275. stripping is enabled, aChar is removed from the string.  Further, if CRLF 
  276. stripping is enabled, any trailing carriage returns or linefeeds are 
  277. removed.  If no string is found, or if the string found is completely 
  278. stripped, this method returns an empty string.
  279.  
  280. If a memory reallocation fails, this method returns NULL.  If the return 
  281. value is NULL, the SktSocketUser has become corrupt, and will crash the 
  282. process the next time it attempts to alter its input queue.  You should 
  283. either free the SktSocket or terminate the process.
  284.  
  285. See also: - getInput:ofLength:, - inputToChar:, - nextInputLine, 
  286. - nextInputLineInZone:, - setDoesStrip:, - doesStrip, 
  287. - setDoesStripCRLF:, - doesStripCRLF
  288.  
  289.  
  290.  
  291. nextInputLine
  292. - (char *) nextInputLine
  293.  
  294. Removes characters from the input queue up to and including the 
  295. delimiter, and returns them as a null-terminated string.  If regular 
  296. stripping is enabled, aChar is removed from the string.  Further, if CRLF 
  297. stripping is enabled, any trailing carriage returns or linefeeds are 
  298. removed.  If no string is found, or if the string found is completely 
  299. stripped, this method returns an empty string.
  300.  
  301. If a memory reallocation fails, this method returns NULL.  If the return 
  302. value is NULL, the SktSocketUser has become corrupt, and will crash the 
  303. process the next time it attempts to alter its input queue.  You should 
  304. either free the SktSocket or terminate the process.
  305.  
  306. See also: - getInput:ofLength:, - inputToChar:, 
  307. - inputToChar:inZone:, - nextInputLineInZone:, - setDoesStrip:, 
  308. - doesStrip, - setDoesStripCRLF:, - doesStripCRLF
  309.  
  310.  
  311.  
  312. nextInputLineInZone:
  313. - (char *) nextInputLineInZone:(NXZone *)aZone
  314.  
  315. Removes characters from the input queue up to and including the 
  316. delimiter, and returns them as a null-terminated string allocated from 
  317. aZone.  If regular stripping is enabled, aChar is removed from the string.  
  318. Further, if CRLF stripping is enabled, any trailing carriage returns or 
  319. linefeeds are removed.  If no string is found, or if the string found is 
  320. completely stripped, this method returns an empty string.
  321.  
  322. If a memory reallocation fails, this method returns NULL.  If the return 
  323. value is NULL, the SktSocketUser has become corrupt, and will crash the 
  324. process the next time it attempts to alter its input queue.  You should 
  325. either free the SktSocket or terminate the process.
  326.  
  327. See also: - getInput:ofLength:, - inputToChar:, 
  328. - inputToChar:inZone:, - nextInputLine, - setDoesStrip:, 
  329. - doesStrip, - setDoesStripCRLF:, - doesStripCRLF
  330.  
  331.  
  332.  
  333. purgeInput
  334. - purgeInput
  335.  
  336. Empties the input queue.  Returns self, or nil if a memory reallocation 
  337. fails.  If the return value is nil, the SktSocketUser has become corrupt, 
  338. and will crash the process the next time it attempts to alter its input 
  339. queue.  You should either free the SktSocket or terminate the process.
  340.  
  341. See also: - queueInput:ofLength:
  342.  
  343.  
  344.  
  345. queueInput:ofLength:
  346. - queueInput:(const char *)input ofLength:(long int)length
  347.  
  348. Appends input to the input queue.  If a queue limit is in effect, the 
  349. number of delimited sequences is counted, and it that number exceeds the 
  350. queue limit, all subsequent delimited sequences are deleted from the 
  351. queue, and any fragmentary portion is advanced to immediately follow 
  352. the delimited sequences.  Returns self, or nil if a memory reallocation 
  353. fails.  If the return value is nil, the SktSocketUser has become corrupt, 
  354. and will crash the process the next time it attempts to alter its input 
  355. queue.  You should either free the SktSocket or terminate the process.
  356.  
  357. The SktSocketUser's SktSocket object sends this message in its getInput 
  358. method.
  359.  
  360. See also: - setDelimiter:, - delimiter, - nextInputLine, 
  361. - nextInputLineInZone:, - setQueueLimit:, - queueLimit
  362.  
  363.  
  364.  
  365. queueLength
  366. - (long int)queueLength
  367.  
  368. Returns the length, in bytes, of the input queue.  Use this method if you 
  369. want to be sure you'll get enough characters from an invocation of 
  370. getInput:ofLength:.
  371.  
  372. See also: - getInput:ofLength:
  373.  
  374.  
  375. queueLimit
  376. - (long int)queueLimit
  377.  
  378. Returns the maximum allowable “lines” in the queue to limit.  Whenever 
  379. new input is queued, the number of delimiters is counted, and if that 
  380. exceeds the queue limit, all subsequent delimited sequences are deleted 
  381. from the queue, and any fragmentary portion is advanced to immediately 
  382. follow the delimited sequences.  If the queue limit is 0 or less, no limit 
  383. checking is performed.
  384.  
  385. See also: - setQueueLimit:, - setDelimiter:, - delimiter
  386.  
  387.  
  388. queueOutput:ofLength:
  389. - queueOutput:(const char *)output ofLength:(long int)length
  390.  
  391. Forwards output to SktSocket's queueOutput:ofLength: method.  You 
  392. should always use this method in your application, rather than directly 
  393. accessing SktSocket's method, since some processing may need to be 
  394. performed by the SktSocketUser before the SktSocket gets the data.  
  395. Returns self, or nil if a memory reallocation fails.  If the return value is 
  396. nil, the SktSocketUser has become corrupt, and will crash the process the 
  397. next time it attempts to alter its input queue.  You should either free the 
  398. SktSocket or terminate the process.
  399.  
  400. See also: - queueOutput:ofLength (SktSocket)
  401.  
  402.  
  403.  
  404. queueOutputString:
  405. - queueOutputString:(const char *)aString
  406.  
  407. Forwards output to SktSocket's queueOutput:ofLength: method.  You 
  408. should always use this method in your application, rather than directly 
  409. accessing SktSocket's method, since some processing may need to be 
  410. performed by the SktSocketUser before the SktSocket gets the data.  
  411. Returns self, or nil if a memory reallocation fails.  If the return value is 
  412. nil, the SktSocketUser has become corrupt, and will crash the process the 
  413. next time it attempts to alter its input queue.  You should either free the 
  414. SktSocket or terminate the process.
  415.  
  416. See also: - queueOutput:ofLength: (SktSocket)
  417.  
  418.  
  419.  
  420. setDelimiter:
  421. - setDelimiter:(char)aChar
  422.  
  423. Sets the character used to delimit lines in the nextInputLine and 
  424. nextInputLineInZone: methds.  Returns self.
  425.  
  426. Changing the delimiter when there is data in the queue and a queue limit 
  427. is in effect is probably not a good idea.
  428.  
  429. See also: - delimiter, - nextInputLine,- nextInputLineInZone:
  430.  
  431.  
  432.  
  433. setDoesStrip:
  434. - setDoesStrip:(BOOL)flag
  435.  
  436. If flag is YES, the SktSocketUser will strip the ...ToChar: character from 
  437. input requested by inputToChar: and inputToChar:inZone:, or the 
  438. delimiter from input requested by nextInputLine and 
  439. nextInputLineInZone:.  If NO, stripping is not done in those methods.  
  440. However, if the ...ToChar: character or the delimiter is either a carriage 
  441. return or a linefeed, and doesStripCRLF is YES, then those will be 
  442. stripped.
  443.  
  444. See also: - doesStrip, - setDoesStripCRLF: - doesStripCRLF
  445.  
  446.  
  447.  
  448. setDoesStripCRLF:
  449. - setDoesStripCRLF:(BOOL)flag
  450.  
  451. If flag is YES, the SktSocketUser will strip all trailing carriage returns 
  452. and linefeeds from input retrieved by any of the inputToChar... or 
  453. nextInputLine... methods.  This stripping is performed after regular 
  454. stripping, so that if regular stripping is not done and the character used to 
  455. retrieve the text is not a carriage return or linefeed, CRLF stripping is 
  456. blocked from occurring.  Returns self.
  457.  
  458. See also: - doesStripCRLF, - setDoesStrip: - doesStrip
  459.  
  460.  
  461.  
  462. setQueueLimit:
  463. - setQueueLimit:(long int)limit
  464.  
  465. Sets the maximum allowable “lines” in the queue to limit.  Whenever 
  466. new input is queued, the number of delimiters is counted, and if that 
  467. exceeds the queue limit, all subsequent delimited sequences are deleted 
  468. from the queue, and any fragmentary portion is advanced to immediately 
  469. follow the delimited sequences.  If the queue limit is set to 0 or less, no 
  470. limit checking is performed.
  471.  
  472. Changing the delimiter when there is date in the queue and a queue limit 
  473. is in effect is probably not a good idea.
  474.  
  475. See also: - queueLimit, - setDelimiter:, - delimiter 
  476.  
  477.  
  478. setSocket:
  479. - (SktSocket *)setSocket:(SktSocket *)aSocket
  480.  
  481. Sets the SktSocket to aSocket, and returns the previous SktSocket.  Also 
  482. has the SktSocket's user set to the SktSocketUser.
  483.  
  484. See also: - initWithSktSocket:, - socket:, - setUser: (SktSocket)
  485.  
  486.  
  487. socket
  488. - (SktSocket *)socket
  489.  
  490. Returns the SktSocketUser's SktSocket's object.
  491.  
  492. See also: - initWithSktSocket:, - setSocket:
  493.  
  494.  
  495.  
  496. ungetInput:ofLength:
  497. - (long int)ungetInput:(char *)input ofLength:(long int)length
  498.  
  499. Adds length bytes from input to the front of the input queue.  Use this 
  500. method to undo the effects of getInput:ofLength:.  Do not use this with 
  501. any other retrieval method—they may strip characters from their returned 
  502. input, which will alter the content of the queue if that data is pushed back.  
  503. Returns self, or nil if a memory reallocation fails.  If the return value is 
  504. nil, the SktSocketUser has become corrupt, and will crash the process the 
  505. next time it attempts to alter its input queue.  You should either free the 
  506. SktSocket or terminate the process.
  507.  
  508. See also: - getInput:ofLength: 
  509.  
  510.  
  511.